home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 April / EnigmA AMIGA RUN 17 (1997)(G.R. Edizioni)(IT)[!][issue 1997-04][EAR-CD].iso / EARCD / comm / mail / YamNet.lha / FSCode.lha / FSCode.Doc < prev    next >
Text File  |  1996-05-11  |  10KB  |  224 lines
  1.  
  2.    NAME
  3.     FSCode -- Encode a binary file using only ASCII characters.
  4.  
  5.    SYNOPSIS
  6.     FSCode FILE/A,TO,E=ENCODE/S,MULTI/S,LINES/N
  7.  
  8.    FUNCTION
  9.     FSCode was born to be a more efficient replacement for uuencode;
  10.     it's purpose is to encode a binary file (for example, an executable
  11.     or an archive such as those made by LhA or Zip) using only the
  12.     standard ASCII character set, i.e. the characters between 32 and 126.
  13.  
  14.     uuencode encodes 3 bytes into 4 characters, enlarging a file by
  15.     33%; FSCode does a better job by encoding 4 bytes (a longword) into
  16.     5 characters: the enlargement is only 25%. This theoretical figure
  17.     does not take into account a couple of control lines and the line
  18.     feeds used to subdivide the resulting file, and two more control
  19.     characters per line needed by uuencode; the real enlargement tends
  20.     to 26.6...% for FSCode and to 37.7...% for uuencode.
  21.  
  22.     It must be made clear that the quantity of information contained in
  23.     the encoded files is exactly the same, so, if you use uuencode or
  24.     FSCode to send binary files into electronic mail messages that will
  25.     be compressed thereafter, the size of the resulting packets will be
  26.     very similar, in perfect accordance to the information theory. The
  27.     advantage is that the message stored on your disk in readable form
  28.     will take less space, and that you will be able to send bigger
  29.     files when there is a limit on the size of a single message.
  30.  
  31.     One more advantage of FSCode over uuencode is that it uses a 32-bit
  32.     CRC to check the correctness of the decoded file; one disadvantage
  33.     is that it doesn't use a per-line checksum, so you won't know
  34.     exactly where the file was corrupted.
  35.  
  36.    INPUTS
  37.     FILE - Input file to encode or decode.
  38.         The file to decode can contain multiple encoded files and/or
  39.         multiple parts of a single file (read further for details).
  40.  
  41.     TO - Destination file for the encoded or decoded data (optional).
  42.         If the destination file is omitted, FSCode will send it's
  43.         output to the standard output (usually the console) when
  44.         encoding, or to the file name specified in the encoded file
  45.         when decoding.
  46.  
  47.         CAUTION: If you specify a destination filename and the file to
  48.         decode contains multiple encoded files, they will be appended
  49.         to the same file, which might not be what you want. It is
  50.         usually better to omit the destination filename and let FSCode
  51.         figure out the correct name as written in the encoded file.
  52.  
  53.     E=ENCODE - A switch that instructs FSCode to encode the input file.
  54.         By default FSCode will try to decode an already encoded file
  55.         and recreate the original file.
  56.  
  57.     M=MULTI - Encode/decode to/from a multi-part file.
  58.         If encoding, FSCode will split the file in blocks made by a
  59.         given number of lines (see the LINES parameter below). If you
  60.         specified a destination file name, FSCode will place every
  61.         block in a separate file, using the specified file name as the
  62.         base part and appending a number: for example, if you specified
  63.         "Hello" as the destination file name, FSCode will create
  64.         "Hello1", Hello2", and so on. If you didn't specify a
  65.         destination file name, the blocks will be sent to the standard
  66.         output one after another. If the file is small enough to fit in
  67.         a single block, FSCode will automatically switch back to
  68.         single-part mode.
  69.  
  70.         If decoding, the MULTI switch instructs FSCode to read several
  71.         files as input: again, FSCode will use the input file name as
  72.         the base part and append a number. Please note that you don't
  73.         have to use the MULTI switch to decode a multi-part file placed
  74.         in a single input file: FSCode is smart enough to recognize it
  75.         and skip any extraneous data. On the other hand, you can decode
  76.         several single-part files at once by giving them suitable names
  77.         and invoking FSCode with the MULTI option.
  78.  
  79.     L=LINES - Set number of lines for multi-part encoding.
  80.         The default is 100 lines, which is just below 8 kb. The
  81.         starting and ending lines are not included, so the resulting
  82.         file will be LINES+2 lines long. The minimum value for this
  83.         parameter is 2.
  84.  
  85.         This parameter is meaningful only when encoding.
  86.  
  87.    RESULT
  88.     FSCode will output a file that looks like this:
  89.  
  90.         !start Example
  91.         E4x~n4MPvGMo9KC4L]7:J^.a,N5B2E###*4
  92.         !end 25 4E9AB940
  93.  
  94.     The first line contains the file name, without drive/directory
  95.     specifications. This is to prevent 1) errors when trying to decode
  96.     a file produced on a system different than yours and 2) funny jokes
  97.     like overwriting system files. The decoding process actually uses
  98.     the complete file name, without removing the drive/directory part
  99.     that might have been added after the encoding: this is to ease the
  100.     creation of scripts and such things for automatic decoding.
  101.  
  102.     The last line contains the size (in decimal) and the 32-bit CRC (in
  103.     hexadecimal) of the original file.
  104.  
  105.     In multi-part mode, each part starts with a line like this:
  106.  
  107.         !mstrt 1/2 Example
  108.  
  109.     where "1/2" means "this is part 1 of a 2-parts file". Notice that
  110.     the magic word is "!mstrt" instead of "!start". The "!end" line has
  111.     the same format in both modes: the only difference is that the size
  112.     and CRC values are partial, i.e. only for the preceeding blocks. It
  113.     has been done this way so that you will know which part is wrong in
  114.     case of a problem.
  115.  
  116.     Should FSCode fail for any reason, an (hopefully) meaningful
  117.     message will be printed on your screen. Examples include `no start
  118.     line' or `CRC mismatch' or `can't open file <file name>'.
  119.  
  120.    NOTES
  121.     FSCode is very tolerant on what you do to the encoded lines,
  122.     provided that you do not add or remove characters in the range from
  123.     33 to 126 [!-~]. You can reflow the lines and insert spaces, line
  124.     feeds or other control characters at will.
  125.  
  126.     FSCode reports inconsistencies in size or CRC but continues the
  127.     decoding process, so if the problem is real you can at least
  128.     recover part of the file.
  129.  
  130.     The absence of the "!end" line does not influence the correctness
  131.     of the decoded file, provided that no characters that could be
  132.     taken as valid follow the real data. Of course you miss the size
  133.     and CRC check, but otherwise the decoding process is not influenced.
  134.  
  135.     In multi-part mode, FSCode will not create the last file if it
  136.     would contain only one line of data: it will append that line to
  137.     the previous file, which will then be one line longer than
  138.     expected.
  139.  
  140.     You can create a single-part file from a multi-part one by
  141.     following these simple steps:
  142.         * join all the parts together;
  143.         * remove all the "!mstrt" and "!end" lines except for the first
  144.           "!mstrt" line and the last "!end" line, and any spurious data
  145.           that might be floating around inbetween two parts;
  146.         * change the first "!mstrt x/y" line to "!start" (in other
  147.           words, make it look like as a single-part starting line).
  148.  
  149.     For a deeper description of the encoding algorithm, see the file
  150.     `Specs.Doc' and the source code.
  151.  
  152.    HISTORY
  153.     37.? - Changed initialization of CRC-32 table from static to
  154.         dynamic. This saves 1 kb of executable size.
  155.  
  156.     37.16 - Added a couple of SetVBuf() calls: this should speed up I/O
  157.         on kickstart V40 and above. SetVBuf() is not implemented on
  158.         prior kickstart versions, but it is harmless to call.
  159.  
  160.     37.17 - Minor improvements, so minor I don't even remember them. ;)
  161.  
  162.     37.18 - Major improvements, including:
  163.         * support for automatic splitting and joining;
  164.         * made faster thanks to improved I/O strategies;
  165.         * can be aborted by pressing CTRL-C;
  166.         * more robust error checking (I hope).
  167.  
  168.         Moreover, the ExtractFile.ems script now checks for the
  169.         presence of the ending line before it starts extraction. The
  170.         previous versions would hang in such a case.
  171.  
  172.     37.19 - The decoder automatically extracts multiple encoded files
  173.         placed in the same input file(s). Somehow I forgot to add this
  174.         nice feature in the previous release.
  175.  
  176.     37.20 - Minor change in CRC-32 routines, affecting only code size.
  177.         FSCode is now completely pure. Previously it wasn't, but it
  178.         worked fine as a residnet program anyway.
  179.  
  180.    DISTRIBUTION
  181.     This program is freeware. You may redistribute it as long as:
  182.      - this text and the source code are included;
  183.      - you don't charge more than a nominal copying fee for
  184.        distribution.
  185.  
  186.     Please state your modifications to the code with a clear comment,
  187.     and send me your modified version. It would be a good idea to
  188.     include the original code, anyway.
  189.  
  190.     Any contribution will be greatly appreciated.
  191.  
  192.    DISCLAIMER
  193.     The author does not assume any responsibility for damages which
  194.     could result by the use or possession of this program. The entire
  195.     risk for the use of this program is assumed by the user.
  196.  
  197.    AUTHOR
  198.     Flavio Stanchina
  199.     Loc. Montevaccino, 39
  200.     38040 Trento (Italia)
  201.  
  202.     Fidonet: 2:333/801.9@fidonet
  203.     e-mail: flavio@iestn.inet.it
  204.  
  205.    ACKNOWLEDGEMENTS
  206.     Thanks to Gian Maria Calzolari (2:332/508.19@fidonet.org) for beta
  207.     testing and suggestions, and for writing a new ExtractFile.ems
  208.     ARexx script for EMS that supports both uuencode and FSCode.
  209.  
  210.     Thanks to Marco Amadori (2:333/408.23@fidonet.org) for beta
  211.     testing, and for the modified UUDecode.spot and UUWrite.spot ARexx
  212.     scripts that support both uuencode and FSCode.
  213.  
  214.     Thanks to Sandro Tolaini (2:332/113.3@fidonet.org) for a bug
  215.     report.
  216.  
  217.     Thanks to Vincenzo Scarpa (2:334/21.20@fidonet.org) for
  218.     FSDecode.spot and FSWrite.spot (so, Spot users, now you have a
  219.     choice).
  220.  
  221.     And finally thanks to all the participants of the AMIGA.ITA Fidonet
  222.     conference for suggestions and encouragement.
  223.  
  224.